TypeScript Authentication: JWT Type Safety Patterns for Global Applications

오늘날의 상호 연결된 세계에서 안전하고 안정적인 글로벌 애플리케이션을 구축하는 것이 가장 중요합니다. 사용자 신원을 확인하는 프로세스인 인증은 중요한 데이터를 보호하고 승인된 액세스를 보장하는 데 중요한 역할을 합니다. JSON 웹 토큰(JWT)은 단순성과 이식성으로 인해 인증을 구현하는 데 널리 사용되는 선택 사항이 되었습니다. TypeScript의 강력한 타입 시스템과 결합하면 특히 대규모 국제 프로젝트의 경우 JWT 인증을 더욱 강력하고 유지 관리 가능하게 만들 수 있습니다.

Why Use TypeScript for JWT Authentication?

TypeScript는 인증 시스템을 구축할 때 다음과 같은 몇 가지 이점을 제공합니다.

• Type Safety: TypeScript의 정적 타이핑은 개발 프로세스 초기에 오류를 포착하여 런타임에 예상치 못한 문제가 발생할 위험을 줄입니다. 이는 인증과 같은 보안에 민감한 구성 요소에 매우 중요합니다.
• Improved Code Maintainability: 유형은 명확한 계약 및 문서를 제공하여 특히 여러 개발자가 참여할 수 있는 복잡한 글로벌 애플리케이션에서 코드를 더 쉽게 이해, 수정 및 리팩터링할 수 있도록 합니다.
• Enhanced Code Completion and Tooling: TypeScript를 인식하는 IDE는 더 나은 코드 완성, 탐색 및 리팩터링 도구를 제공하여 개발자 생산성을 향상시킵니다.
• Reduced Boilerplate: 인터페이스 및 제네릭과 같은 기능은 상용구 코드를 줄이고 코드 재사용성을 개선하는 데 도움이 될 수 있습니다.

Understanding JWTs

JWT는 두 당사자 간에 전송될 클레임을 나타내는 작고 URL 안전한 수단입니다. 세 부분으로 구성됩니다.

1. Header: 알고리즘과 토큰 유형을 지정합니다.
2. Payload: 사용자 ID, 역할 및 만료 시간과 같은 클레임이 포함되어 있습니다.
3. Signature: 비밀 키를 사용하여 토큰의 무결성을 보장합니다.

JWT는 각 요청에 대해 데이터베이스를 쿼리할 필요 없이 서버 측에서 쉽게 확인할 수 있기 때문에 일반적으로 인증에 사용됩니다. 그러나 중요한 정보를 JWT 페이로드에 직접 저장하는 것은 일반적으로 권장되지 않습니다.

Implementing Type-Safe JWT Authentication in TypeScript

TypeScript에서 타입 안전한 JWT 인증 시스템을 구축하기 위한 몇 가지 패턴을 살펴보겠습니다.

1. Defining Payload Types with Interfaces

JWT 페이로드의 구조를 나타내는 인터페이스를 정의하여 시작합니다. 이렇게 하면 토큰 내에서 클레임에 액세스할 때 타입 안전성을 확보할 수 있습니다.

interface JwtPayload {
  userId: string;
  email: string;
  roles: string[];
  iat: number; // Issued At (timestamp)
  exp: number; // Expiration Time (timestamp)
}

이 인터페이스는 JWT 페이로드의 예상되는 모양을 정의합니다. 토큰 유효성 관리에 중요한 표준 JWT 클레임인 `iat`(발행 시간) 및 `exp`(만료 시간)를 포함했습니다. 사용자 역할 또는 권한과 같이 애플리케이션과 관련된 다른 클레임을 추가할 수 있습니다. 토큰 크기를 최소화하고 보안을 개선하기 위해 클레임을 필요한 정보로만 제한하는 것이 좋습니다.

Example: Handling User Roles in a Global E-commerce Platform

전 세계 고객에게 서비스를 제공하는 전자 상거래 플랫폼을 고려해 보십시오. 사용자에 따라 역할이 다릅니다.

• Admin: 제품, 사용자 및 주문을 관리할 수 있는 전체 액세스 권한이 있습니다.
• Seller: 자신의 제품을 추가하고 관리할 수 있습니다.
• Customer: 제품을 찾아보고 구매할 수 있습니다.

`JwtPayload`의 `roles` 배열을 사용하여 이러한 역할을 나타낼 수 있습니다. `roles` 속성을 보다 복잡한 구조로 확장하여 사용자의 액세스 권한을 세분화된 방식으로 나타낼 수 있습니다. 예를 들어 사용자가 판매자로 운영할 수 있는 국가 목록 또는 사용자가 관리자 액세스 권한을 가진 상점 배열을 가질 수 있습니다.

2. Creating a Typed JWT Service

JWT 생성 및 확인을 처리하는 서비스를 만듭니다. 이 서비스는 `JwtPayload` 인터페이스를 사용하여 타입 안전성을 보장해야 합니다.

import jwt from 'jsonwebtoken';

const JWT_SECRET = process.env.JWT_SECRET || 'your-secret-key'; // Store securely!

class JwtService {
  static sign(payload: Omit, expiresIn: string = '1h'): string {
    const now = Math.floor(Date.now() / 1000);
    const payloadWithTimestamps: JwtPayload = {
        ...payload,
        iat: now,
        exp: now + parseInt(expiresIn) * 60 * 60,
    };
    return jwt.sign(payloadWithTimestamps, JWT_SECRET);
  }

  static verify(token: string): JwtPayload | null {
    try {
      const decoded = jwt.verify(token, JWT_SECRET) as JwtPayload;
      return decoded;
    } catch (error) {
      console.error('JWT verification error:', error);
      return null;
    }
  }
}

이 서비스는 두 가지 방법을 제공합니다.

• `sign()`: 페이로드에서 JWT를 만듭니다. `iat` 및 `exp`가 자동으로 생성되도록 `Omit`를 사용합니다. `JWT_SECRET`를 안전하게 저장하는 것이 중요합니다. 이상적으로는 환경 변수 및 비밀 관리 솔루션을 사용합니다.
• `verify()`: JWT를 확인하고 유효한 경우 디코딩된 페이로드를 반환하고 유효하지 않은 경우 `null`을 반환합니다. `jwt.verify` 메서드는 오류를 발생시키거나(`catch` 블록에서 잡힘) 정의한 페이로드 구조와 일치하는 객체를 반환하기 때문에 확인 후 타입 어설션 `as JwtPayload`를 사용합니다.

Important Security Considerations:

• Secret Key Management: 코드에 JWT 비밀 키를 하드 코딩하지 마십시오. 환경 변수 또는 전용 비밀 관리 서비스를 사용하십시오. 키를 정기적으로 순환하십시오.
• Algorithm Selection: HS256 또는 RS256과 같은 강력한 서명 알고리즘을 선택하십시오. `none`과 같은 약한 알고리즘을 피하십시오.
• Token Expiration: 손상된 토큰의 영향을 제한하기 위해 JWT에 적절한 만료 시간을 설정하십시오.
• Token Storage: 클라이언트 측에서 JWT를 안전하게 저장하십시오. 옵션에는 HTTP 전용 쿠키 또는 XSS 공격에 대한 적절한 예방 조치를 취한 로컬 스토리지가 포함됩니다.

3. Protecting API Endpoints with Middleware

`Authorization` 헤더에서 JWT를 확인하여 API 엔드포인트를 보호하는 미들웨어를 만듭니다.

import { Request, Response, NextFunction } from 'express';

interface RequestWithUser extends Request {
  user?: JwtPayload;
}

function authenticate(req: RequestWithUser, res: Response, next: NextFunction) {
  const authHeader = req.headers.authorization;

  if (!authHeader) {
    return res.status(401).json({ message: 'Unauthorized' });
  }

  const token = authHeader.split(' ')[1]; // Assuming Bearer token
  const decoded = JwtService.verify(token);

  if (!decoded) {
    return res.status(401).json({ message: 'Invalid token' });
  }

  req.user = decoded;
  next();
}

export default authenticate;

이 미들웨어는 `Authorization` 헤더에서 JWT를 추출하고 `JwtService`를 사용하여 확인하고 디코딩된 페이로드를 `req.user` 객체에 첨부합니다. 또한 Express.js에서 표준 `Request` 인터페이스를 확장하는 `RequestWithUser` 인터페이스를 정의하여 `JwtPayload | undefined` 타입의 `user` 속성을 추가합니다. 이렇게 하면 보호된 경로에서 사용자 정보에 액세스할 때 타입 안전성이 제공됩니다.

Example: Handling Time Zones in a Global Application

애플리케이션에서 다른 시간대의 사용자가 이벤트를 예약할 수 있다고 가정해 보겠습니다. 이벤트 시간을 올바르게 표시하기 위해 사용자의 선호 시간대를 JWT 페이로드에 저장할 수 있습니다. `JwtPayload` 인터페이스에 `timeZone` 클레임을 추가할 수 있습니다.

interface JwtPayload {
  userId: string;
  email: string;
  roles: string[];
  timeZone: string; // e.g., 'America/Los_Angeles', 'Asia/Tokyo'
  iat: number;
  exp: number;
}

그런 다음 미들웨어 또는 경로 처리기에서 `req.user.timeZone`에 액세스하여 사용자 기본 설정에 따라 날짜 및 시간을 포맷할 수 있습니다.

4. Using the Authenticated User in Route Handlers

보호된 경로 처리기에서 이제 완전한 타입 안전성으로 `req.user` 객체를 통해 인증된 사용자의 정보에 액세스할 수 있습니다.

import express, { Request, Response } from 'express';
import authenticate from './middleware/authenticate';

const app = express();

app.get('/profile', authenticate, (req: Request, res: Response) => {
  const user = (req as any).user; // or use RequestWithUser
  res.json({ message: `Hello, ${user.email}!`, userId: user.userId });
});

이 예제에서는 `req.user` 객체에서 인증된 사용자의 이메일과 ID에 액세스하는 방법을 보여줍니다. `JwtPayload` 인터페이스를 정의했기 때문에 TypeScript는 `user` 객체의 예상 구조를 알고 타입 검사 및 코드 완성을 제공할 수 있습니다.

5. Implementing Role-Based Access Control (RBAC)

보다 세분화된 액세스 제어를 위해 JWT 페이로드에 저장된 역할을 기반으로 RBAC를 구현할 수 있습니다.

function authorize(roles: string[]) {
  return (req: RequestWithUser, res: Response, next: NextFunction) => {
    const user = req.user;

    if (!user || !user.roles.some(role => roles.includes(role))) {
      return res.status(403).json({ message: 'Forbidden' });
    }

    next();
  };
}

이 `authorize` 미들웨어는 사용자의 역할에 필요한 역할이 포함되어 있는지 확인합니다. 그렇지 않으면 403 Forbidden 오류를 반환합니다.

app.get('/admin', authenticate, authorize(['admin']), (req: Request, res: Response) => {
  res.json({ message: 'Welcome, Admin!' });
});

이 예제에서는 사용자가 `admin` 역할을 갖도록 요구하여 `/admin` 경로를 보호합니다.

Example: Handling Different Currencies in a Global Application

애플리케이션에서 금융 거래를 처리하는 경우 여러 통화를 지원해야 할 수 있습니다. 사용자의 선호 통화를 JWT 페이로드에 저장할 수 있습니다.

interface JwtPayload {
  userId: string;
  email: string;
  roles: string[];
  currency: string; // e.g., 'USD', 'EUR', 'JPY'
  iat: number;
  exp: number;
}

그런 다음 백엔드 로직에서 `req.user.currency`를 사용하여 가격을 포맷하고 필요에 따라 통화 변환을 수행할 수 있습니다.

6. Refresh Tokens

JWT는 설계상 수명이 짧습니다. 사용자가 자주 로그인하지 않도록 하려면 새로 고침 토큰을 구현하십시오. 새로 고침 토큰은 사용자가 자격 증명을 다시 입력하지 않고도 새 액세스 토큰(JWT)을 얻는 데 사용할 수 있는 수명이 긴 토큰입니다. 새로 고침 토큰을 데이터베이스에 안전하게 저장하고 사용자와 연결하십시오. 사용자 액세스 토큰이 만료되면 새로 고침 토큰을 사용하여 새 토큰을 요청할 수 있습니다. 이 프로세스는 보안 취약점을 피하기 위해 신중하게 구현해야 합니다.

Advanced Type Safety Techniques

1. Discriminated Unions for Fine-Grained Control

경우에 따라 사용자의 역할 또는 요청 유형에 따라 다른 JWT 페이로드가 필요할 수 있습니다. 판별된 유니온은 타입 안전성으로 이를 달성하는 데 도움이 될 수 있습니다.

interface AdminJwtPayload {
  type: 'admin';
  userId: string;
  email: string;
  roles: string[];
  iat: number;
  exp: number;
}

interface UserJwtPayload {
  type: 'user';
  userId: string;
  email: string;
  iat: number;
  exp: number;
}

type JwtPayload = AdminJwtPayload | UserJwtPayload;

function processToken(payload: JwtPayload) {
  if (payload.type === 'admin') {
    console.log('Admin email:', payload.email); // Safe to access email
  } else {
    // payload.email is not accessible here because type is 'user'
    console.log('User ID:', payload.userId);
  }
}

이 예제에서는 두 개의 다른 JWT 페이로드 타입인 `AdminJwtPayload` 및 `UserJwtPayload`를 정의하고 이를 판별된 유니온 `JwtPayload`로 결합합니다. `type` 속성은 판별자 역할을 하여 페이로드 타입에 따라 속성에 안전하게 액세스할 수 있도록 합니다.

2. Generics for Reusable Authentication Logic

페이로드 구조가 다른 여러 인증 체계가 있는 경우 제네릭을 사용하여 재사용 가능한 인증 로직을 만들 수 있습니다.

interface BaseJwtPayload {
  userId: string;
  iat: number;
  exp: number;
}

function verifyToken(token: string): T | null {
  try {
    const decoded = jwt.verify(token, JWT_SECRET) as T;
    return decoded;
  } catch (error) {
    console.error('JWT verification error:', error);
    return null;
  }
}

const adminToken = verifyToken('admin-token');
if (adminToken) {
  console.log('Admin email:', adminToken.email);
}

이 예제에서는 `BaseJwtPayload`를 확장하는 제네릭 타입 `T`를 사용하는 `verifyToken` 함수를 정의합니다. 이를 통해 모든 토큰에 최소한 `userId`, `iat` 및 `exp` 속성이 있는지 확인하면서 다른 페이로드 구조로 토큰을 확인할 수 있습니다.

Global Application Considerations

글로벌 애플리케이션을 위한 인증 시스템을 구축할 때 다음 사항을 고려하십시오.

• Localization: 오류 메시지 및 사용자 인터페이스 요소가 다른 언어 및 지역에 맞게 현지화되었는지 확인하십시오.
• Time Zones: 토큰 만료 시간을 설정하고 날짜와 시간을 사용자에게 표시할 때 시간대를 올바르게 처리하십시오.
• Data Privacy: GDPR 및 CCPA와 같은 데이터 개인 정보 보호 규정을 준수하십시오. JWT에 저장된 개인 데이터의 양을 최소화하십시오.
• Accessibility: 장애가 있는 사용자가 액세스할 수 있도록 인증 흐름을 설계하십시오.
• Cultural Sensitivity: 사용자 인터페이스 및 인증 흐름을 설계할 때 문화적 차이를 염두에 두십시오.

Conclusion

TypeScript의 타입 시스템을 활용하여 글로벌 애플리케이션을 위한 강력하고 유지 관리 가능한 JWT 인증 시스템을 구축할 수 있습니다. 인터페이스로 페이로드 타입을 정의하고, 타입화된 JWT 서비스를 만들고, 미들웨어로 API 엔드포인트를 보호하고, RBAC를 구현하는 것은 보안 및 타입 안전성을 보장하는 데 필수적인 단계입니다. 현지화, 시간대, 데이터 개인 정보 보호, 접근성 및 문화적 감수성과 같은 글로벌 애플리케이션 고려 사항을 고려하여 다양하고 국제적인 대상에게 포괄적이고 사용자 친화적인 인증 환경을 만들 수 있습니다. 안전한 키 관리, 알고리즘 선택, 토큰 만료 및 토큰 스토리지를 포함하여 JWT를 처리할 때 항상 보안 모범 사례를 우선시하십시오. TypeScript의 기능을 활용하여 글로벌 애플리케이션을 위한 안전하고 확장 가능하며 안정적인 인증 시스템을 구축하십시오.